NbConvert

Command line usage

NbConvert is the library, and the command line tool that allow to convert from notebook to other formats. It is a technological preview in 1.0 but is already usable and highly configurable. It ships already with many default available formats : html, latex, markdown, python, rst and slides which are fully base on Jinja templating engine, so writing a converter for your custom format or tweeking the existing one should be extra simple.

You can invoke nbconvert by doing

$ ipython nbconvert <options and arguments>

Call ipython nbconvert with the --help flag or no aruments to get basic help on how to use it. For more information about configuration use the --help-all flag

Basic export

We will be converting Custom Display Logic.ipynb. Be sure to have runed some of the cells in it to have output otherwise you will only see input in nbconvert. Nbconvert do not execute the code in the notebook files, it only converts what is inside.



In [1]:

    
!ipython nbconvert  'Working With Markdown Cells.ipynb'









    



[NbConvertApp] Using existing profile dir: u'/home/fperez/.ipython/profile_default'
[NbConvertApp] Converting notebook Working With Markdown Cells.ipynb to html
[NbConvertApp] Support files will be in Working With Markdown Cells_files/
[NbConvertApp] Loaded template full.tpl
[NbConvertApp] Writing 194531 bytes to Working With Markdown Cells.html

Html is the default value (that can be configured) , so the verbose form would be



In [2]:

    
!ipython nbconvert  --to=html 'Working With Markdown Cells.ipynb'









    



[NbConvertApp] Using existing profile dir: u'/home/fperez/.ipython/profile_default'
[NbConvertApp] Converting notebook Working With Markdown Cells.ipynb to html
[NbConvertApp] Support files will be in Working With Markdown Cells_files/
[NbConvertApp] Loaded template full.tpl
[NbConvertApp] Writing 194531 bytes to Working With Markdown Cells.html

You can also convert to latex, which will take care of extractin the embeded base64 encoded png, or the svg and call inkscape to convert those svg to pdf if necessary :



In [3]:

    
!ipython nbconvert  --to=latex 'Working With Markdown Cells.ipynb'









    



[NbConvertApp] Using existing profile dir: u'/home/fperez/.ipython/profile_default'
[NbConvertApp] Converting notebook Working With Markdown Cells.ipynb to latex
[NbConvertApp] Support files will be in Working With Markdown Cells_files/
[NbConvertApp] Loaded template article.tplx
[NbConvertApp] Writing 16660 bytes to Working With Markdown Cells.tex

You should just have to compile the generated .tex file. If you get the required packages installed, if should compile out of the box.

For convenience we allow to run extra action after the conversion has been done, in particular for latex we have a pdf post-processor. You can define the postprocessor tu run with the --post flag.



In [4]:

    
!ipython nbconvert  --to=latex 'Working With Markdown Cells.ipynb' --post=pdf









    



[NbConvertApp] Using existing profile dir: u'/home/fperez/.ipython/profile_default'
[NbConvertApp] Converting notebook Working With Markdown Cells.ipynb to latex
[NbConvertApp] Support files will be in Working With Markdown Cells_files/
[NbConvertApp] Loaded template article.tplx
[NbConvertApp] Writing 16660 bytes to Working With Markdown Cells.tex
[NbConvertApp] Building PDF
[NbConvertApp] Running pdflatex 3 times: [u'pdflatex', u'Working With Markdown Cells.tex']
[NbConvertApp] Running bibtex 1 time: [u'bibtex', u'Working With Markdown Cells']
[NbConvertApp] WARNING | bibtex had problems, most likely because there were no citations
[NbConvertApp] Removing temporary LaTeX files
[NbConvertApp] PDF successfully created

Have a look at 04 - Custom Display Logic.pdf, toward the end, where we compared display() vs display_html() and returning the object. See how the cell where we use display_html was not able to display the circle, whereas the two other ones were able to select one of the oher representation they know how to display.

Customizing template

let's look at the first 20 lines of the python exporter



In [11]:

    
pyfile = !ipython nbconvert --to python 'Working With Markdown Cells.ipynb' --stdout
for l in pyfile[20:40]:
    print l









    



#     - Sublist
#         - This
#   - Sublist
#         - That
#         - The other thing
# * Two
#   - Sublist
# * Three
#   - Sublist
# 
# Now another list:
# 
# 1. Here we go
#     1. Sublist
#     2. Sublist
# 2. There we go
# 3. Now this

# You can add horizontal rules:
#

We see that the non-code cell are exported to the file. To have a cleaner script, we will export only the code contained in the code cells.

To do so, we will inherit the python template, and overwrite the markdown blocks to be empty.



In [12]:

    
%%writefile simplepython.tpl
{% extends 'python.tpl'%}

{% block markdowncell -%}
{% endblock markdowncell %}

## we also want to get rig of header cell
{% block headingcell -%}
{% endblock headingcell %}

## and let's change the appearance of input prompt
{% block in_prompt %}
# This was input cell with prompt number : {{ cell.prompt_number if cell.prompt_number else ' ' }}
{%- endblock in_prompt %}









    



Writing simplepython.tpl



In [14]:

    
pyfile = !ipython nbconvert --to python 'Working With Markdown Cells.ipynb' --stdout --template=simplepython.tpl

for l in pyfile[4:40]:
    print l
print '...'









    



# coding: utf-8
...

Get rid of all command line flags.

As of all of IPython nbconvert can be configured using profiles and passing the --profile flag. Moreover if a config.py file exist in current working directory nbconvert will use that, or read the config file you give to it with the --config=<file> flag.

In the end, if you are often running nbconvert on the same project, $ ipython nbconvert should be enough to get you up and ready.